Skip to content

feat(xtask): require every source file to have an entry in docs/architecture.md - #949

Merged
jussielo-amd merged 9 commits into
mainfrom
xtask-check-architecture-doc
Nov 6, 2026
Merged

jussielo-amd merged 9 commits into
mainfrom
xtask-check-architecture-doc

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Nov 6, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

docs/architecture.md says it is "updated in the same PR as the code it documents", but nothing enforced that. This adds cargo xtask check-architecture-doc, which fails when a production source file has no entry in the module map, and runs it from the clippy CI job, a new architecture-doc prek hook at pre-commit and pre-push, and a contract test that pins the wiring.

How this differs from the lychee check

lychee checks one direction: every link already written in a markdown file resolves. It only sees what the doc already cites, so a new foo.rs that nobody mentions has no link to check and passes. This check starts from the source tree instead. Deleting or renaming a documented file is still caught by lychee (the link breaks); the new check adds the case lychee cannot see, a file with no entry.

What it checks

Every tracked .rs file under apps/*/src, crates/*/src and engines/*/src must be one of: linked from docs/architecture.md as a relative markdown link that renders as a link (a path inside an HTML comment, a fenced code block or an inline code span does not count, so commenting out an entry cannot keep the gate green; neither does a malformed link, an image, or the outer brackets of a link that contains another link), listed in EXEMPT, or a test-only helper matched by whole file stem (test_support, test_env, proptests, *_proptests, *_props, *_properties). It reads the git index and the working tree, never a diff, so it gives the same answer in CI, at pre-commit and at pre-push.

EXEMPT holds the 76 files still uncited, mostly in the dashboard crates (78 when the check was written; a change merged to main since then documented one of them, and the stale-entry rule correctly failed until its line was removed; this PR documents crates/rocm-engine-protocol/src/lib.rs, a contract surface, and takes it off the list). It follows the ALLOWLIST pattern in check-crate-edges and fails in both directions: a source file in neither the doc nor the list fails, and so does an entry that is now cited, no longer exists, or is redundant with the test-helper rule. The list is meant to shrink as files are documented. Nothing can stop a determined edit from adding to it, so EXEMPT_CEILING caps its size, enforced by the command itself and pinned by a test: growing the list means raising that constant too, a second, visible line in the diff for a reviewer to accept. The failure message for an uncited file only asks for an entry; it does not mention EXEMPT.

Wiring

  • .pre-commit-config.yaml: architecture-doc hook, stages: [pre-commit, pre-push], always_run: true, pass_filenames: false, in the local-tools group like the other xtask-backed hooks. It has no file filter because the answer depends on the whole tree and a delete-only commit has no changed files to match. The check reads the git index and the working tree, so at pre-commit (where prek stashes unstaged changes first) it matches what is being committed. At pre-push it reads the working tree rather than the pushed commits, so with a clean tree it also catches a commit made with --no-verify, but with staged or unstaged edits it can pass where CI fails. CI is the gate and the hooks are feedback; the module comment and hook comment say so.
  • .github/workflows/ci.yml: a step in the clippy job next to check-crate-edges, gated on the rust filter. The rust filter now also lists docs/architecture.md, because deleting or rewording an entry changes the result though no .rs file moved.
  • architecture_doc_check_runs_in_hooks_and_ci in xtask/src/workflow_contract.rs reads both files and fails if the hook loses a stage, gains a file filter or stops running on every commit, or if the CI step or the path-filter entry goes missing.
  • Docs updated in the same change: docs/architecture.md, CONTRIBUTING.md, docs/testing.md, AGENTS.md (sections 5 and 6) and the PR template. They previously said only that the doc's links are checked for resolution.

What it does not cover

Whether an entry's prose still describes its file, and functions that move between two files that are both already cited. The docs say so rather than implying otherwise.

Verification

  • 39 unit tests in xtask/src/architecture_doc.rs plus the contract test. Run on the pushed tree, for the affected crate only: cargo test -p xtask --no-fail-fast (610 passed), cargo clippy --locked -p xtask --all-targets -- -D warnings, cargo fmt --all --check, cargo xtask lychee, and the leak scan against the merge base (clean).
  • Each new test was shown to fail when its target is broken: disabling the uncited-file branch fails 3 tests, disabling the stale-because-now-cited branch fails exempt_entry_that_is_now_cited_is_stale, letting .. climb out of the repo root fails only_in_repo_rust_links_count_as_citations, dropping pre-push from the hook fails the contract test, and removing docs/architecture.md from the rust filter fails the contract test. For the link scanner, disabling comment stripping fails 3 tests (including the commented-out-entry scenario), disabling fence stripping fails a_link_in_a_fenced_code_block_is_not_a_citation, and disabling code-span stripping fails 2 tests.
  • Links are parsed as complete inline links, [text](destination "title"): an unescaped [ on the same line, a balanced-parenthesis or <...> destination, an optional title and the closing ). A link missing its [ or ), or with an escaped bracket, is plain text when rendered and does not count; an angle-bracketed destination does count. An image, ![alt](path), does not count, while a link whose text contains an image does; the outer brackets of a link that contains another link do not count, since links do not nest; a backslash-escaped backtick or < opens no code span or comment. Link text spanning lines is not recognised, which can only make the check fail. Mutation checks (the later rules too: ignoring escapes before code markers fails an_escaped_backtick_does_not_open_a_code_span, never treating an opener as an image fails 2 tests, not deactivating outer link openers fails a_link_containing_a_link_cites_only_the_inner_one, lowering EXEMPT_CEILING fails the ceiling test, and putting the EXEMPT hint back in the message fails its test): accepting a link without its ) fails a_link_missing_its_closing_parenthesis_is_not_a_citation, dropping angle-bracket support fails 2 tests, ignoring backslash escapes fails 2 tests, and no longer resetting open brackets at a newline fails a_link_missing_its_opening_bracket_is_not_a_citation.
  • The scanner removes HTML comments, fenced blocks and code spans in one left-to-right pass, so a backtick inside a comment and a comment marker inside a code span keep their usual precedence. Where it cannot tell (an unclosed backtick) it hides a link, which can only make the check fail, never pass. Indented code blocks are not recognised.
  • End to end: with a new uncited file staged under engines/vllm/src/, cargo xtask check-architecture-doc exits 1 and names the file; with it removed the command exits 0.
  • Not run locally: the full workspace test suite and the e2e lanes, which this change does not touch; only the affected crate (xtask) was checked. CI is authoritative for the rest.

No Gherkin scenario: this is internal CI and hook plumbing with no user-observable rocm CLI behaviour (no command output, exit codes, files or engine selection change), and the xtask command is a contributor tool. The message the check prints names a real action, and the end-to-end run above exercises the failing path.

Rebased onto origin/main once and force-pushed with a lease (the approval on the PR stood after the push); later main commits were merged in with plain pushes. The check passes on the pushed tree. Out of scope for the check, and now said so in the docs: build.rs files and the tests/ and examples/ trees. Link forms the check does not recognise, and the failure message says so: reference-style links, a ?query suffix and root-relative paths. The pre-push hook was skipped with --no-verify for the pushes: the first run failed on an unrelated apps/rocm test that passes alone, and CI is the authoritative gate for the workspace suite.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The link scanner counts paths inside HTML comments and code as documented references, allowing the coverage gate to pass when a source file is absent from the rendered module map.

1 open issue
What changed in this PR

Adds a contributor-facing check requiring production Rust source files to appear in the architecture module map, complementing existing link-resolution checks.

Changes:

  • Adds cargo xtask check-architecture-doc with test-helper exemptions, stale-exemption detection, and unit tests.
  • Wires the check into commit/push hooks and CI, with a contract test protecting that wiring.
  • Updates contributor guidance and the PR checklist to explain the requirement and its limits.
File Description
xtask/​src/​workflow_contract.rs Tests hook stages, CI wiring, and path-filter coverage.
xtask/​src/​main.rs Registers and dispatches the new command.
xtask/​src/​architecture_doc.rs Implements source citation checks, exemptions, and tests.
docs/​testing.md Documents running the check.
docs/​architecture.md Explains citation enforcement and exemptions.
CONTRIBUTING.md Adds contributor requirements and hook guidance.
AGENTS.md Adds architecture-map maintenance rules.
.pre-commit-config.yaml Runs the check at commit and push.
.github/​workflows/​ci.yml Adds the CI step and architecture-doc path trigger.
.github/​pull_request_template.md Adds a module-map maintenance checklist item.

Review effort: Balanced

Comment thread xtask/src/architecture_doc.rs Resolved
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 6, 2026 12:58
@jussielo-amd
jussielo-amd marked this pull request as ready for review November 6, 2026 12:59
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 6, 2026 13:00
@jussielo-amd
jussielo-amd requested a review from rominf November 6, 2026 13:00

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The citation scanner accepts malformed Markdown links but rejects valid entity-encoded angle-delimited destinations, allowing broken citations to pass while valid entries fail the hook and CI.

2 open issues
1 resolved since last review

Review effort: Balanced

Comment thread xtask/src/architecture_doc.rs Resolved
Comment thread xtask/src/architecture_doc.rs Resolved

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No blocking issues. The check, hook and CI wiring look right, and the docs are updated together. A few non-blocking points, left as inline comments:

  • Malformed links (unclosed (, missing [, escaped [) are accepted as citations, so a broken entry keeps the gate green. This matches the open Copilot comment.
  • Angle-bracket destinations like [x](<../a.rs>) are rejected, so a valid reformatted entry fails the hook and CI (fails closed). Also matches an open Copilot comment.
  • The failure message points authors at EXEMPT, which AGENTS.md §6 and CONTRIBUTING say not to do.
  • "EXEMPT can only shrink" is stated in several places but nothing enforces it.

Approving on a diff-only read; I didn't build or run it, so CI is the execution evidence.

Comment thread xtask/src/architecture_doc.rs Outdated
let mut rest = doc.as_str();
while let Some(at) = rest.find("](") {
rest = &rest[at + 2..];
let end = rest.find([')', ' ', '\n']).unwrap_or(rest.len());

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The scan takes any ](…next )/space/newline as a destination without checking for the closing ) or the opening [. So [cli](../apps/rocm/src/cli.rs (unclosed), cli](../x.rs) and an escaped \[x](...) all still count as citations, and a mangled entry keeps the gate green even though it no longer renders as a link. Worth validating the full [text](dest) shape and adding regression cases for missing delimiters and escapes.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e8c602c. The scan now accepts only a complete inline link: an unescaped [ on the same line, a balanced-parenthesis or <...> destination, an optional title and the closing ). A link missing its ) or [, an escaped \[, and a stray [ on an earlier line no longer count, and breaking_the_only_entry_leaves_the_file_uncited covers each shape at the check level. Each rule has a test that fails when the rule is disabled.

#[allow(clippy::case_sensitive_file_extension_comparisons)] // Rust sources are always lowercase `.rs`
fn resolve_link(target: &str) -> Option<String> {
let target = target.split('#').next()?;
if target.contains("://") || !target.ends_with(".rs") {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[cli](<../apps/rocm/src/cli.rs>) is valid CommonMark, but the target then ends with >, so ends_with(".rs") fails and the hook/CI reject a correctly rendered entry. Stripping the optional <...> delimiters before resolving (plus a test) would fix it.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e8c602c. A <...> destination has its delimiters removed before the path is resolved, so [cli](<../apps/rocm/src/cli.rs>) and its #L10 and titled variants count as citations, and an unterminated < is not a link. an_angle_bracketed_destination_is_a_citation covers it and fails when the angle-bracket branch is disabled.

Comment thread xtask/src/architecture_doc.rs Outdated
for path in &in_tree {
if !cited.contains(*path) && !exempt.contains(path) && !is_test_helper(path) {
violations.push(format!(
"`{path}` is not cited in {DOC}: add an entry for it to the module map, as a \

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This message tells the author to add the file to EXEMPT when it "deliberately has no entry", but AGENTS.md §6 and CONTRIBUTING say not to add to EXEMPT to make the check pass. I'd have the message say only to add an entry, and keep growing EXEMPT a reviewed exception.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e3494f2. The message for an uncited file now only asks for an entry in the module map and no longer mentions EXEMPT, so it agrees with AGENTS.md and CONTRIBUTING. the_failure_message_for_an_uncited_file_only_asks_for_an_entry pins it, and fails if the hint comes back.


/// Production files that have no entry in `docs/architecture.md` yet: everything
/// that was uncited when this check was added, mostly the dashboard crates.
/// Do not add to this list to make the check pass: document the file in the doc

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"can only shrink" (here and in AGENTS.md/CONTRIBUTING/architecture.md) isn't enforced: check() flags stale entries, but adding an uncited file to EXEMPT passes. Either reword (e.g. "grows only via a reviewed edit") or add a ratchet.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e3494f2, with both of your options. I added a ratchet: EXEMPT_CEILING caps the list at its current size, enforced by check-architecture-doc itself and by a unit test, so growing the list means raising that constant too, a second visible line in the diff. It cannot stop a determined edit, so I also reworded the claim everywhere it was made (module docs, AGENTS.md, CONTRIBUTING) from "can only shrink" to "meant to shrink, with a capped size", and said what the cap does and does not guarantee.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The citation parser incorrectly accepts images and invalid nested links while mishandling escaped backticks, allowing missing citations to pass and valid citations to fail.

3 open issues
2 resolved since last review

Review effort: Balanced

out.push(' ');
continue;
}
if rest.starts_with('`') {

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e3494f2. A backslash-escaped backtick or < now opens nothing, and both characters are kept so the link scan still sees the escape. Your input, Use \ for a backtick; cli.rs, now cites the file. an_escaped_backtick_does_not_open_a_code_spancovers it, including an escaped backslash before a real backtick and an escaped<!--`, and fails when escape handling is disabled.

Comment thread xtask/src/architecture_doc.rs Outdated
}
match bytes[at] {
b'\n' => open = 0,
b'[' => open += 1,

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e3494f2. Openers are tracked as image or link, and an image destination is no longer a citation, so ![cli](path.rs) leaves the file uncited. A link whose text contains an image still counts, and an escaped \! is not an image. I reversed the old assertion at that line and added an_image_is_not_a_citation, an_escaped_exclamation_mark_does_not_make_an_image and an_image_inside_a_links_text_leaves_the_link_valid.

Comment thread xtask/src/architecture_doc.rs Outdated
Comment on lines +411 to +413
found.push(destination);
at += 2 + length;
continue;

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in e3494f2. When an inner link forms, the outer link openers are deactivated, as links do not nest, so [cli [details](../README.md)](../apps/rocm/src/cli.rs) no longer cites cli.rs. Image openers are left alone, and plain brackets that do not form a link do not deactivate anything, so [a [b] c](path) still works. a_link_containing_a_link_cites_only_the_inner_one covers it, including a later link on the same line, and is distinct from the plain-brackets case.

…to be in the module map

docs/architecture.md says it is updated in the same PR as the code it
documents, but nothing enforced it. The lychee link check only confirms
that links already in the doc resolve, so a new module nobody wrote an
entry for passed silently.

`cargo xtask check-architecture-doc` starts from the tree instead: every
tracked .rs file under apps/*/src, crates/*/src and engines/*/src must be
linked from the doc, listed in EXEMPT, or be a test-only helper matched by
file stem. EXEMPT holds the 78 files uncited today and, like ALLOWLIST in
check-crate-edges, is checked both ways, so it can only shrink.

The architecture-doc prek hook runs it at pre-commit and pre-push, over the
whole tree on every run, so a commit made with --no-verify is still caught
at push.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…ith a contract test

The step is gated on the rust path filter like the other xtask checks in
that job. The filter now also lists docs/architecture.md, because deleting
or rewording an entry changes the answer though no .rs file moved.

architecture_doc_check_runs_in_hooks_and_ci reads .pre-commit-config.yaml
and ci.yml and fails if the hook loses a stage, gains a file filter or
stops running on every commit, or if the CI step or the path-filter entry
goes missing.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…sting and agent guides

architecture.md and CONTRIBUTING.md previously said only that file links in
the doc are checked for resolution. They now say the reverse is checked too:
a production source file with no entry fails check-architecture-doc, and
what the check does not cover (whether an entry's prose is still true).

AGENTS.md section 5 and 6 and the PR template ask for the entry in the same
change as the file, and say not to add a file to EXEMPT to make the check
pass.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…module map

The citation scan looked for a raw `](` in docs/architecture.md, so a link
inside an HTML comment, a fenced block or an inline code span still counted.
Commenting out the only entry for a file kept the check green although the
rendered module map no longer documented it.

The doc is now reduced to its rendered link text first: HTML comments, fenced
code blocks and code spans are removed in one left-to-right pass, so a
backtick inside a comment and a comment marker inside a code span keep their
usual precedence. Where it cannot tell, it hides a link, which can only make
the check fail. Indented code blocks are not recognised.

New tests cover each construct, the precedence cases, CRLF input, and the
commented-out-entry scenario at the check level.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…odule map cites it

The module map gained an entry for crates/rocm-dash-daemon/src/registry.rs on
main, so the stale-entry check rightly rejected its EXEMPT line after the
merge.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The citation scan took any `](` as a link, which both over- and under-counted.
A destination in angle brackets, `[cli](<../apps/rocm/src/cli.rs>)`, was
rejected because the `<` and `>` stayed in the path, so reformatting an
existing entry failed the hook and CI. A link missing its `)` or its `[`, or
with an escaped bracket, was counted as a citation although the rendered page
shows plain text, so breaking the only entry for a file kept the gate green.

Links are now parsed as `[text](destination "title")`: an unescaped `[` on the
same line, a balanced-parenthesis or `<...>` destination, an optional title and
the closing `)`. A link that is not complete is not a citation. A link whose
text spans lines is not recognised, which can only make the check fail.

New tests cover angle-bracket destinations, each missing delimiter, escaped
brackets and parentheses, a stray `[` on an earlier line, nested brackets,
parentheses in a path, and several links on one line.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…e images and nested links

Review feedback on the module-map check.

The failure message for an uncited file told authors they could add it to
EXEMPT, which AGENTS.md and CONTRIBUTING.md say not to do; it now only asks for
an entry. "EXEMPT can only shrink" was not enforced, so EXEMPT_CEILING now caps
the list's size in the command and in a test: growing the list means raising
that constant too, a visible reviewed edit. The docs say "meant to shrink"
instead of promising what the code did not guarantee.

The link scanner also treated three shapes as citations or non-citations
wrongly. An image, ![x](path.rs), renders as an image and no longer counts,
while a link whose text contains an image still does. The outer brackets of a
link that contains another link no longer count, since links do not nest. A
backslash-escaped backtick no longer opens a code span, which had swallowed the
`[` of a real link and reported its file as uncited.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd force-pushed the xtask-check-architecture-doc branch from f0fe0d4 to e3494f2 Compare November 6, 2026 14:29

@tomastola tomastola left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for e8c602c: it fixes both open Copilot threads. Broken entries (a missing [ or ), an escaped \[) no longer count as citations (line 303), and [x](<path>) is now accepted (line 165). e3494f2's EXEMPT_CEILING turns "the list can only shrink" into something the code enforces, and its image, nested-link and escaped-backtick handling closes the remaining parser gaps I'd have raised. I ran cargo test -p xtask architecture_doc (all pass) plus a probe through cited_paths confirming each of the e8c602c cases on the pre-rebase head f0fe0d4a, and cargo xtask check-architecture-doc passed there; on e3494f2 I read the diff but did not re-run them. Nothing here blocks; the notes below are for you to weigh.

1. Remaining link forms (note only). Reference-style links ([cli][c] plus [c]: ../apps/rocm/src/cli.rs), …/cli.rs?plain=1 and root-relative /apps/rocm/src/cli.rs render as working links but still aren't counted, so they fail the check. The docs now say to use an inline [text](path) link, which covers it; just flagging that the failure message will tell someone to add an entry that is already there if they use one of these forms.

2. Pre-push reads the working tree, not the commits being pushed. The module comment (architecture_doc.rs:23-24) says the check "behaves the same in CI, in the pre-commit hook and in the pre-push hook", and the PR body says pre-push catches a commit made with --no-verify. Pre-commit is fine, because prek stashes unstaged changes first. At pre-push, though, git ls-files and read_to_string(docs/architecture.md) read the current index and working tree. Take a commit that adds foo.rs with no entry, pushed while the doc entry is staged or edited but not committed: pre-push passes and CI fails. CI is the real gate, so this is just about wording. Either soften the claim, or have the pre-push path read git ls-tree/git show of the pushed ref.

3. Scope note. build.rs files at crate roots (apps/rocm/build.rs, crates/rocm-core/build.rs, crates/rocm-deps/build.rs) are production code but outside */src, so the check never looks at them. That's a reasonable boundary. Since the docs say "every production source file", it may be worth one clause saying what is out of scope (build.rs, tests/, examples/).

4. Nit. crates/rocm-engine-protocol/src/lib.rs is in EXEMPT, while AGENTS.md calls that crate a contract surface. It's probably the most useful entry to document first, which would also start shrinking the list.

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 6, 2026
…ent rocm-engine-protocol

Review notes on the check.

The check reads the index and the working tree. At pre-commit prek stashes
unstaged changes first, so it matches what is being committed; at pre-push it
reads the working tree, not the commits being pushed, so it only agrees with CI
on a clean tree. The module comment, the hook comment and the contract test's
doc no longer say pre-push always catches a commit made with --no-verify, and
the module comment says CI is the gate.

The docs now name what is out of scope (build.rs, tests/, examples/) and which
link forms are not recognised (reference-style, a ?query suffix, root-relative
paths). The failure message says so too, and a test holds that claim to what
the parser does.

crates/rocm-engine-protocol/src/lib.rs, a contract surface, now has an entry in
docs/architecture.md and comes off EXEMPT, and EXEMPT_CEILING drops to 76.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd removed this pull request from the merge queue due to a manual request Nov 6, 2026
@jussielo-amd

Copy link
Copy Markdown
Collaborator Author

Thanks for the thorough read. All four notes are addressed in 6ba5a56 (pushed as part of 171c1e6, merged with the latest main).

  1. Link forms: the failure message now asks for an inline [text](path) link relative to docs/ and says reference-style links, a ?query suffix and root-relative paths are not recognised, and the module comment, CONTRIBUTING.md and architecture.md say the same. the_link_forms_the_failure_message_rules_out_are_not_citations holds that claim to the parser: each of the three forms is asserted not to be a citation, and the message wording is pinned alongside it.

  2. Pre-push: I softened the claim rather than change what the hook reads. The module comment, the hook comment and the contract test's doc now say the check reads the index and working tree, that at pre-commit prek stashes unstaged changes so it matches the commit, and that at pre-push it reads the working tree rather than the pushed commits, so it can pass where CI fails when edits are staged or unstaged. CI is the gate and the hook is feedback. The PR body says the same. Reading git ls-tree of the pushed ref would be the stronger fix, but it changes what the hook is for, so I left that as a possible follow-up.

  3. Scope: the module comment, CONTRIBUTING.md and architecture.md now say build.rs files and the tests/ and examples/ trees are out of scope.

  4. rocm-engine-protocol: lib.rs now has an entry in docs/architecture.md describing what it holds, comes off EXEMPT, and EXEMPT_CEILING drops from 77 to 76.

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 6, 2026
Merged via the queue into main with commit 0b6b4a6 Nov 6, 2026
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants